<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libconfini: INSTALL</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">libconfini
   </div>
   <div id="projectbrief">Yet another INI parser</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">INSTALL </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>How to install and use <b>libconfini</b> on different platforms</p>
<p><a class="anchor" id="md_dev_docs_install"></a></p>
<h1>Unix </h1>
<p>On most Unix-like systems, you should be able to install <b>libconfini</b> using the following common steps: </p><pre class="fragment">./configure
make
make install-strip
</pre><p> If the <code>strip</code> utility is not available on your machine, use <code>make install</code> instead (it will produce larger binaries)</p>
<p>For a minimum installation without development files (i.e. static libraries, headers, documentation, examples, etc.) use <code>./configure --disable-devel</code>. If you only want to leave out man pages and examples, use <code>./configure --disable-doc --disable-examples</code>.</p>
<p>If you need to customize the target directories, or otherwise adjust the build setting, use </p><pre class="fragment">./configure --help
</pre><p> to list the configure options.</p>
<p>After running the <code>configure</code> script you can print the list of commonly used targets by launching <code>make help</code>.</p>
<p>If the <code>configure</code> script is missing you need to generate it by running the <code>bootstrap</code> script. Use the <code>--noconfigure</code> parameter to prevent <code>bootstrap</code> from automatically running the <code>configure</code> script immediately after having generated it. To list different options use <code>./bootstrap --help</code>.</p>
<p>If both the <code>configure</code> and <code>bootstrap</code> scripts are missing you can initialize the build environment by launching the following commands from the source directory: </p><pre class="fragment">libtoolize
aclocal
automake --add-missing --copy --gnu
autoconf
./configure
</pre><p> Or you can use a more modern approach and launch directly: </p><pre class="fragment">mkdir m4
autoreconf -i
./configure
</pre><h1>Microsoft Windows </h1>
<h2>MinGW</h2>
<p>If you are using Microsoft Windows, a batch script for compiling <b>libconfini</b> with MinGW without GNU Make is available (<code>mgwmake.bat</code>). If you want instead to compile the library manually, you can run: </p><pre class="fragment">cd src
windres.exe -i winres.rc -o winres.o
gcc.exe -std=c99 -g -O3 -Wall -shared -static-libgcc -Wl,--no-undefined \
    -Wl,-out-implib,libconfini.lib -o libconfini.dll winres.o confini.c
strip.exe libconfini.dll
</pre><p> If you want to generate also the <code>.def</code> file, use: </p><pre class="fragment">cd src
windres.exe -i winres.rc -o winres.o
gcc -c -o confini.o confini.c
dlltool.exe -z libconfini.def -D libconfini --export-all-symbols confini.o
gcc.exe -std=c99 -g -O3 -Wall -shared -static-libgcc -Wl,--no-undefined \
    -Wl,-out-implib,libconfini.lib -o libconfini.dll confini.o winres.o
strip.exe libconfini.dll
</pre><p> If you want to build (and install) <b>libconfini</b> via GNU Make under Microsoft Windows several options are available, such as MinGW + MSYS, MSYS2 (which ships <a href="https://packages.msys2.org/base/mingw-w64-libconfini">an official port</a> of the library, Cygwin (for which <a href="https://github.com/fd00/yacp/tree/master/libconfini">an unofficial port</a> of <b>libconfini</b> exists) and GnuWin32.</p>
<h2>Microsoft Visual Studio</h2>
<p>To compile the library with Microsoft Visual Studio the <code>msvcmake.bat</code> batch script is available (please make sure to run it with the right environment variables). If you want instead to compile the library manually, you can run: </p><pre class="fragment">cd src
rc.exe winres.rc
cl.exe /c /O2 confini.c
link /DLL /DEF:libconfini.def /OUT:libconfini.dll winres.res confini.obj
</pre><p> To create a static library use instead: </p><pre class="fragment">cd src
rc.exe winres.rc
cl.exe /c /O2 confini.c
lib.exe /OUT:libconfini.lib winres.res confini.obj
</pre><p> In both cases, to test the library with a simple program named <code>my_test.c</code> you can launch: </p><pre class="fragment">cl.exe my_test.c /link libconfini.lib
</pre><p> The library is written in standard C99; however MSVC uses an exotic semantics to access the <code>.data</code> segment of a shared library. Accordingly, after having generated the DLL file, to access its global variables you will need to replace all occurrences of the <code>extern</code> keyword with the special <code>__declspec(dllimport)</code> keyword in the library's header included in your program. This can be easily done using the C Preprocessor:</p>
<div class="fragment"><div class="line"><span class="comment">/*  my_test.c  */</span></div>
<div class="line"> </div>
<div class="line"><span class="preprocessor">#pragma push_macro(&quot;extern&quot;</span>)</div>
<div class="line"><span class="preprocessor">#undef extern</span></div>
<div class="line"><span class="preprocessor">#define extern __declspec(dllimport)</span></div>
<div class="line"><span class="preprocessor">#include &lt;<a class="code" href="confini_8h.html">confini.h</a>&gt;</span></div>
<div class="line"><span class="preprocessor">#pragma pop_macro(&quot;extern&quot;</span>)</div>
<div class="ttc" id="aconfini_8h_html"><div class="ttname"><a href="confini_8h.html">confini.h</a></div><div class="ttdoc">libconfini header</div></div>
</div><!-- fragment --><p>The code above will work if you are using the library in a C program. But, as the macro will affect also the language-specific directive <code>extern "C"</code>, it will not work under C++. In this last case you will have to edit the header by hand and place the above macro inside <code>extern "C" { ... }</code>. This workaround is not required with more standard-compliant compilers (GCC, Clang).</p>
<h2>Precompiled DLL</h2>
<p>Often a compiled DLL <a href="https://github.com/madmurphy/libconfini/releases">is available</a> among the assets of each release of the library. The DLL asset usually contains a header file already sanitized for Microsoft Visual Studio and a set of DLLs built using different optimizations and compilers. Unless you used a C++ compiler for compiling the library (we didn't and you shouldn't, the library is written in C99, not in C++), a binary built with GCC (MinGW) will be linkable from a Microsoft Visual Studio project (you may rename the <code>.dll.a</code> file extension to <code>.lib</code> for that).</p>
<h1>Bare metal </h1>
<p>The library has almost everything implemented from scratch, with the only notable exception of the I/O functions <code><a class="el" href="confini_8h.html#a7d5042d3044dfb5a34a6bfc5af3a882d" title="Parse an INI file and dispatch its content to a custom callback using a FILE structure as argument.">load_ini_file()</a></code> and <code><a class="el" href="confini_8h.html#a54be108d26619db3066ce1c000dc8a17" title="Parse an INI file and dispatch its content to a custom callback using a path as argument.">load_ini_path()</a></code>, which rely on C standard libraries. On some platforms, however, only a rather exotic I/O API is available, while for some other platforms the C Standard Library is simply too heavy or just not implementable.</p>
<p>In these situations it will be needed to get rid of every tie with the C Standard Library and compile <b>libconfini</b> as "bare metal". The <code>configure</code> script has two options for creating special forks of the original library able to function in any environment, <code>--without-io-api</code> and <code>--without-libc</code>. For information about how to proceed, please see <code>dev/hackings/baremetal/README.md</code>.</p>
<h1>Comparison of different compilers </h1>
<p>In all the tests so far GCC always produced the fastest binary. Clang produced a binary about 10% slower (with both <code>-O2</code> and <code>-O3</code>), whereas Microsoft Visual Studio lay far behind.</p>
<h1>Complex installations </h1>
<p>This package has been designed to be able to coexist with other major releases of itself. However, when two versions share the same major number but have different minor or revision numbers, only the most recent package must be installed.</p>
<p>For two or more different major releases to be able to coexist, the major number of each version must be appended to the package name it refers to, with the possible exception of only one package (usually version 1.X.X). This can be done easily by passing the <code>--with-other-versions</code> option to the <code>configure</code> script: </p><pre class="fragment">./configure --with-other-versions
</pre><p> This will ensure <b>libconfini</b> X.Y.Z to be installed as <b>libconfiniX</b> X.Y.Z.</p>
<p>There are different views concerning which package name should be the only unnumbered one. According to some conventions the major version number is appended to the package names of all major version greater than one, while according to other conventions the major version number is appended to the package names of all versions that are older than the current version.</p>
<p>If you want to install a modified version of <b>libconfini</b> without generating conflicts with an original version already present in the system, or you simply want to install <b>libconfini</b> under a different name, you can use <a href="https://www.gnu.org/software/automake/manual/html_node/Renaming.html">Autoconf transforming rules</a>. In particular, to prepend a prefix to the library name, use <code>./configure --program-prefix=[PREFIX]</code>; to append a suffix, use <code>./configure --program-suffix=[SUFFIX]</code>; to perform a <code>sed</code> substitution, use <code>./configure --program-transform-name="s/[OLDTEXT]/[NEWTEXT]/[g]"</code>. Note that the <code>lib</code> prefix at the beginning of the library name is always preserved (for instance, <code>./configure --program-transform-name="s/^.*$/hello/"</code> will rename the package to "libhello"). If you specify a prefix and/or a suffix together with a <code>sed</code> substitution, the latter will be performed after the former have been concatenated to the original name.</p>
<p>Do not use Autoconf transforming rules in place of the built-in <code>./configure --with-other-versions</code> for appending the major version number to the name of the package. If you do so, the header file will be installed as <code>confiniX.h</code>, instead of the more standard <code>confini-X.h</code>.</p>
<p>For any issue, drop a message at <a href="https://github.com/madmurphy/libconfini/issues">https://github.com/madmurphy/libconfini/issues</a>.</p>
<h1>Distributing the source code </h1>
<p>If you aim to re-distribute the source code of <b>libconfini</b> you should first make sure that the <code>configure</code> script is present, for granting the possibility to compile the package without having Autotools installed. If the <code>configure</code> script is present and you have already launched it, use <code>make distclean</code> to reset the configuration that this has created, or use <code>make dist</code> to build a fresh archive that ignores the current configuration.</p>
<h1>Distributing the compiled package </h1>
<p>Use <code>make binary-release</code> to create a binary package of <b>libconfini</b> for a particular platform. If you want to obtain the list of the files that are going to be installed, use <code>make manifest</code>. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1
</small></address>
</body>
</html>
